gh-144837: Improve documentation for more collection methods#144841
gh-144837: Improve documentation for more collection methods#144841serhiy-storchaka wants to merge 3 commits intopython:mainfrom
Conversation
Use uniform standard signature syntax in the tutorial and in the array and collections modules documentation.
| .. method:: append(value, /) | ||
|
|
||
| Append a new item with value *x* to the end of the array. | ||
| Append a new item with the specified value to the end of the array. |
There was a problem hiding this comment.
| Append a new item with the specified value to the end of the array. | |
| Append a new item with the specified *value* to the end of the array. |
There was a problem hiding this comment.
Not sure about this. I tried to avoid value *value*.
Doc/tutorial/datastructures.rst
Outdated
|
|
||
|
|
||
| .. method:: list.index(x[, start[, end]]) | ||
| .. method:: list.index(value[, start[, stop]) |
There was a problem hiding this comment.
This still has square brackets? Also, they are unbalanced.
There was a problem hiding this comment.
Good catch! I copied it from other place which already had such error.
As for the signature of the index() methods, this is a different issue. First, we need to decide if it needs to support None (see #138134), or this is just an unintentional implementation artifact. If yes, then we can write
list.index(value, start=None, stop=None, /)
If not, then we need to write
list.index(value, start=0, stop=sys.maxsize, /)
or use multiple signatures:
list.index(value, start=0, /)
list.index(value, start, stop, /)
This is a separate large issue.
|
When you're done making the requested changes, leave the comment: |
Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
serhiy-storchaka
left a comment
serhiy-storchaka
left a comment
There was a problem hiding this comment.
I have made the requested changes; please review again.
Doc/tutorial/datastructures.rst
Outdated
|
|
||
|
|
||
| .. method:: list.index(x[, start[, end]]) | ||
| .. method:: list.index(value[, start[, stop]) |
There was a problem hiding this comment.
Good catch! I copied it from other place which already had such error.
As for the signature of the index() methods, this is a different issue. First, we need to decide if it needs to support None (see #138134), or this is just an unintentional implementation artifact. If yes, then we can write
list.index(value, start=None, stop=None, /)
If not, then we need to write
list.index(value, start=0, stop=sys.maxsize, /)
or use multiple signatures:
list.index(value, start=0, /)
list.index(value, start, stop, /)
This is a separate large issue.
serhiy-storchaka
force-pushed
the
docs-collections-signatures
branch
from
7ac12f6 to
e0fe9c7
Compare
3 participants
Use uniform standard signature syntax in the tutorial and in the array and collections modules documentation.
📚 Documentation preview 📚: https://cpython-previews--144841.org.readthedocs.build/